<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>

  <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
  <title>http request format</title>


</head>


<body>

<h2>URL format for XMLHttpRequest in COID</h2>

<br>

&nbsp;&nbsp;&nbsp;&nbsp; The httpserv service forwards
requests in
certain format to the COID server via the tunnelmgr
service.&nbsp;The
format is described here.<br>

<br>

<h3>Creating or binding to an instance of COID service</h3>

&nbsp;&nbsp;&nbsp; Creating an instance of a service/class
running within the COID server:<br>

<br>

<table style="text-align: left; width: 640px; height: 62px;" border="1" cellpadding="2" cellspacing="2">

  <tbody>

    <tr>

      <td style="background-color: rgb(255, 255, 204);"><code>&nbsp;
&nbsp; http://<span style="font-style: italic; font-weight: bold;">host</span>/path?coid-<span style="color: rgb(51, 204, 255);">o</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="#commfmt">O</a>=<span style="font-style: italic;"><span style="font-weight: bold;">service[:version]</span><br>

      </span></code><code>&nbsp; &nbsp;
http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="color: rgb(51, 204, 255);">o</span>a</code><code>.<span style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);">O</span>=<span style="font-style: italic; font-weight: bold;">service</span><span style="font-weight: bold;"><span style="font-style: italic;">[:version]</span>,</span><span style="font-style: italic; font-weight: bold;">arg1,arg2...</span></code></td>

    </tr>

  </tbody>
</table>

<br>

Where I and O should be specification of input and output protocol
format. For example, specifying<br>

<code>&nbsp;&nbsp;&nbsp;&nbsp;</code><code>?coid-</code><code>oa.x=testserv<br>

</code>means that input (a) is comming as&nbsp;part of the
URL after
mandatory stuff like service name, and output (x) should be in xml
format. Supported formats are specified in <a href="#commfmt">communication
formats</a>.<br>

<br>

Service name, what is actually the name of your class served by COID
server, comes as <span style="font-style: italic;">service</span>
argument, and optionally can contain desired version to open. COID can
serve different versions of the same service in the same time.<br>

<br>

With the input protocol format set to <span style="font-weight: bold;">a</span>,
optional arguments required by the service constructor can be provided
within the URL, after the service name and comma. You can use the GET
http request in this case. With other protocols you have to use a
POST&nbsp;request with body containing the input data.<br>

<br>

The open request, if succesful, returs a unique session identifier in
the Session-Coid http header. This identifier is then used to identify
the session when calling service methods.<br>

<code></code><br>

<h3>Executing methods</h3>

&nbsp;&nbsp;&nbsp; The format for executing service/class
methods is
similar,&nbsp;except that you will specify session id and method
name
or id instead of the service name. The session id (ssid) was given by
the server in Session-Coid http header when creating or binding a
service instance.<br>

<br>

<table style="text-align: left; width: 640px; height: 62px;" border="1" cellpadding="2" cellspacing="2">

  <tbody>

    <tr>

      <td style="background-color: rgb(255, 255, 204);"><code>&nbsp;
&nbsp; http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="color: rgb(51, 204, 255);">c</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">O</a>=<span style="font-style: italic;"><span style="font-weight: bold;">ssid,method</span><br>

      </span></code><code>&nbsp; &nbsp;
http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="color: rgb(51, 204, 255);">c</span>a</code><code>.<span style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);">O</span>=<span style="font-style: italic; font-weight: bold;">ssid</span><span style="font-weight: bold;"><span style="font-style: italic;"></span>,</span><span style="font-style: italic; font-weight: bold;">method,arg1,arg2...<br>

      </span></code><code>&nbsp; &nbsp;
http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="color: rgb(51, 204, 255);">c</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">O</a>=<span style="font-style: italic;"><span style="font-weight: bold;">,method</span></span></code></td>

    </tr>

  </tbody>
</table>

<br>

It's possible to omit the ssid argument, if the ssid is being specified
within Session-Coid header of the method call request, but comma before
the method name must be present anyway.<br>

<br>

The <span style="font-style: italic; font-weight: bold;">method</span>
argument can be either a method name, or a method id.<br>

<br>

<br>

<h3>Getting list of available services/classes</h3>

&nbsp;&nbsp;&nbsp; Following request format can be used to
retrieve list of served services/classes:<br>

<br>

<table style="text-align: left; width: 640px;" border="1" cellpadding="2" cellspacing="2">

  <tbody>

    <tr>

      <td style="background-color: rgb(255, 255, 204);"><code>&nbsp;
&nbsp; http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="font-family: mon; color: rgb(51, 204, 255);">s</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">O</a><span style="font-style: italic;"><span style="font-weight: bold;"></span></span></code><br>

      <code>&nbsp; &nbsp; http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="font-family: mon; color: rgb(51, 204, 255);">s</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">O</a>=<span style="font-style: italic;"><span style="font-weight: bold;">service</span></span></code></td>

    </tr>

  </tbody>
</table>

<br>

The first form returns all available services, the second one checks
for all available versions of requested service, or it can be used to
check the availability of specified class.<br>

<br>

<br>

<h3>Getting list of methods available in service/class</h3>

&nbsp;&nbsp;&nbsp; To get a list of methods of certain
service, the following request format is used:<br>

<br>

<table style="text-align: left; width: 640px;" border="1" cellpadding="2" cellspacing="2">

  <tbody>

    <tr>

      <td style="background-color: rgb(255, 255, 204);"><code>&nbsp;
&nbsp; http://<span style="font-style: italic; font-weight: bold;">host</span>/</code><code>path?coid-</code><code><span style="font-family: mon; color: rgb(51, 204, 255);">m</span><a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">I</a>.<a style="font-weight: bold; text-decoration: underline; color: rgb(51, 51, 255);" href="http_request_format.html#commfmt">O</a>=<span style="font-style: italic;"><span style="font-weight: bold;">service</span></span></code></td>

    </tr>

  </tbody>
</table>

<br>

<h3><a name="commfmt"></a>Protocol&nbsp;formats</h3>

Supported communication format codes<br>

<table style="text-align: left; width: 640px;" border="1" cellpadding="2" cellspacing="2">

  <tbody>

    <tr>

      <th style="text-align: center;">code</th>

      <th style="text-align: center;">format</th>

      <th style="text-align: center;">note</th>

    </tr>

    <tr>

      <td style="font-family: monospace; text-align: center; font-weight: bold;">x</td>

      <td>xml</td>

      <td>lightweight xml as described in <a href="formatting_stream.html#xml">xml formatting stream<br>

      </a>other xml protocols would begin with 'x' followed by
another character, for example xr for xml-rpc, xs for samba, etc.</td>

    </tr>

    <tr>

      <td style="font-family: monospace; text-align: center; font-weight: bold;">j</td>

      <td>json</td>

      <td><a href="formatting_stream.html#json">json</a>
formatted output, can be handed over to javascript eval function as <code>eval('('+transport.responseText+')')</code>
that builds js object representation out of it.</td>

    </tr>

    <tr>

      <td style="font-family: monospace; text-align: center; font-weight: bold;">c</td>

      <td>cxx</td>

      <td colspan="1" rowspan="2">cxx format as described <a href="formatting_stream.html#cxx">here</a>.<br>
Used mainly for sending information to the server, mostly when not
bothering with the metadata information - just sending primitive values
in the proper order.</td>

    </tr>

    <tr>

      <td style="font-family: monospace; text-align: center; font-weight: bold;">t</td>

      <td>cxx w/o metadata, newline separated values, semicolon separated array elements</td>


    </tr>

    <tr>

      <td style="font-family: monospace; text-align: center; font-weight: bold;">a</td>

      <td>cxx w/o metadata, as above, within URL</td>

      <td>as above, input only - trailing part of URL</td>

    </tr>

  </tbody>
</table>

<br>

<br>

</body>
</html>
